Aminet 22/Aminet 22 (1997)(GTI - Schatztruhe)[!][Dec 1997].iso/Aminet/comm/bbs/dat_h15e.lha/HydraBBSA15_Part_e.lha/HBBS/Developer/Developer.Readme

Text File | 1997-08-22 | 6KB | 132 lines

Yo, thanks for looking at this file..  To create any doors for HBBS
you really should get hold of the full source code to it, when you have
got that you'll be able to see loads of examples and figure out what does
what better!


But for now I'll give you a few instructions on how to create external
programs (Doors) for HBBS.
==============================================================================


To create a door all you have to do is this:

1) go to wb, find HBBS:Source/Doors_User/!NewDoor

2) select icon/copy from the menu to create a copy of the directory and
   all the files that are in it..

3) rename it to the name of your door

3b) if your door is called NOT called by a user typing a command
    at the BBS command prompt then it should go in Doors_System instead
    (e.g. FrontEnd)

4) open your new directory, in it you will see several files, the
   important ones are:  Main.C, Build, !NukeObjects!, and Update.  Update and
   !NukeObjects! are just amigados scripts to move files to
   HBBS:Doors/[User|System]/<yourdoordir>/<yourdoorname>.HBBS and to
   delete #?.o respectivly..

5) load the file "Update" into a text editor and edit it so that
   it copies the file called "Main", that the compiler produces, to the right
   place.

6) now you need to set your door up so that hbbs can run it, to do this you
   need to edit a file in any Commands directory, there's one in each
   conference, one in each node directory and one in HBBS:commands.  The file
   you need to edit depends on a) what type of door it is and b) what the
   minimum access level a user must have before thay can run it.   If it is a
   system door then you'll need to edit the file called "System" in any
   commands dir.  If it's a user door then you'll need to edit either
   "Level_Global" (all users can use it no matter what their access level is)
   or "Level_<acslevel>" where <acslevel> is the minimum access level a user
   must have to run your door.

   E.G. "Level_50"

   Once you've decided which file you need to edit just load it up into a
   text editor.
7) you now need to add a few lines to the file, these are as follows

  <Command>_Type_<num>=NORMAL
  <Command>_Door_<num>=<door file>

  the following parameters are optional.

  <Command>_Debug_<num>=YES|NO
  <Command>_Params_<num>=<some parameters for your door>

  here's an example for a joinconf door:

  J_Type_1=NORMAL
  J_Door_1=HBBS:Doors/User/Download/Download.HBBS J_Debug_1=NO

  J_Type_2=NORMAL
  J_Door_2=HBBS:Doors/User/Stats/Stats.HBBS J_Params_2=JOINEDCONF

  <num> (above) means the order in which the doors are run, you can run as many
  doors one after the other as you like, if your door fails and another
  following door relies on your door's output then just call
  DOOR_Continue(FALSE); and the following doors will not get run (see the
  download door's source for an example..

  the <params> are passed to your door as N_ND->CurrentDoor->SystemOptions,
  it's just a string so you can just parse it as you would a normal string.

8) thats it!..  it sounds complicated but it really is incredibly
   easy and simple..

  Note: if you want to use a source code debugger on your door then you can set
  <command>_Debug_<num> to YES or TRUE (or ON :-) and when the door is called,
  a window will open on the control screen's window telling you what parameters
  to run your program with..   so if you are using CPR (line debugger with SAS/C)
  then call your door as CPR <door> <nodenum> <params> and bob's your uncle..  a
  bit easier than /x :-)


Here's couple more tips to get you going..

when you write strings to the bbs you can use either DOOR_SysopText(string) or
DOOR_WriteText(string), you *MUST* use CR+LF ("\r\n") at the end of a line. not
just "\n", (this is due to comms packages and the console.device... and it's
not just HBBS that needs this..   Use DOOR_SysopText(string) to display stuff
on the sysop's watch window ONLY, or use DOOR_WriteText(string) to write stuff
to the serial port *AND* the sysop's watch window.

check out DOOR_GetLine(), this is the main thing you use to get input from the
user, at the moment the user cannot use thier cursor keys for anything other
than line editing or scrolling through thier command history,  so (for example)
you can't use cursor up to scroll back when you are looking through the
filelists.   This will change soon, I'll just add another flag value that
you'll be able to specify (something like GL_RAWKEY)..

to read a line of text, with history, and timeout after 20 secs, max len 80
chars and a prompt string of "Banana" do this:

DOOR_GetLine(GL_DISPLAY|GL_EDIT|GL_HISTORY,'\0',80,20,"Banana");

getline returns different numbers depending on what happened, check out
HBBS:Source/Common/Defines.h and search for IN_#?

e.g.  a timeout returns IN_TIMEOUT, a normal line would be IN_GOTLINE, or
IN_LOSSCARRIER.

after EVERY call to DOOR_GetLine() you *MUST*, and I mean *MUST*, check the
status of N_ND->OnlineStatus, if it is not equal to OS_ONLINE then your door
must exit *without* sending *ANY* more data to the serial port..

then, if the user is still on-line, the string returned will be placed in
N_ND->CurrentLine which is a pointer to a null terminated string.

I cannot express just HOW important this is, if you don't do the online checking
your door will cause the bbs to stop responding and may even cause crashes.

When you have written your door you should login locally to a node and hangup
at every point in your program that your door uses door_getline().

Also check out HBBS_LoadConfig(), HBBS_CreateConfig(), HBBS_GetSetting(),
HBBS_AddCfgItem(), HBBS_RemoveCfgItem(), HBBS_SaveConfig(), and
HBBS_FlushConfig() for some COOOOOL standard configuration file loading
and saving routines, check out Node_Main.C for some examples....